Metrics files next to the model, and release 1.13.0 - #46

Adds an optional metrics file next to the model, <stem>.metrics.yml, with its own spec (metrics spec 0.1.0) and JSON Schema. It is the engine half of "metrics next to the model", decided on 6 Oct 2026; the studio builds its Metrics tab on top of it next. The full list is in the 1.13.0 CHANGELOG entry.

What it adds

• The format. Four kinds of metric:

  • a simple aggregation of a column;
  • a row count;
  • a ratio of totals;
  • arithmetic over metric names (expression), the one documented exception to "nothing encoded in a string".

  Simple metrics and row counts take a where filter with eq, ne, in, not_in, gt, gte, lt, lte, between and is_null, combined with any and all, with nulls as in SQL. A filter may name a column on any table the metric's table reaches many-to-one, along exactly one path. Every measure column also yields an inferred metric, named as the studio's semantic export names them today.

• model2data.metrics, the public API: load/validate, and resolve into one semantic representation (entities, relationships, dimensions, measures, metrics with their join paths). Also known_values, to_ossie and write_metric_tests.

• Known values. Computed with DuckDB over the generated data, overall and per month, with the same SQL the dbt tests run. Counts are exact; everything else is rounded to 6 places, half to even.

• CLI.

  • validate checks *.metrics.yml, against the model beside it by default.
  • generate --metrics FILE adds metric_values.json, one dbt test per metric in data-tests/metrics/, and an Ossie file in osi/.
  • metrics list and metrics export --to ossie work without generating.

• Apache Ossie export, 0.1.1 as tagged osi-0.1.1-rc1. No final 0.1.1 tag exists yet. What Ossie has no field for goes into custom_extensions and is listed at the top of the file. Every example is checked against the vendored Ossie schema (Apache-2.0, with its LICENSE and NOTICE).

• Docs: README, README_PYPI, LLMS.md, the guide text, the spec README, PUBLISHING.md rows for /spec/metrics/0.1.0/, and the CHANGELOG.

Determinism

• The generator never reads the metrics file. No existing hash in determinism.json moved; two cases were added.
• --metrics only adds files. test_metrics_only_add_files checks that every file shared with a run without it is byte-identical.

Decisions made while building

• format: percent expects a fraction (0.6 shows as 60%), as BI tools do, and is never multiplied.
• The metric tests live in data-tests/metrics/, because that is the generated project's test-paths.
• generate does not pick up a metrics file beside the model on its own, so an unchanged command keeps writing the same files.
• Order comparisons are refused on text columns too, because collation differs per warehouse.
• Ossie datasets point at the engine's staging models (staging.stg_<table>).

Checked

• Full suite: 2129 passed. ruff, ty and pre-commit are clean.
• A real dbt build on four cases passes every metric test, including defects over several days. A known value moved past its tolerance makes its test fail.

Not verified

• dbt Core 1.12 reading the osi/ folder, and Snowflake's OSI import.
• The metric tests on Postgres. The Postgres CI job only seeds and runs.

After merge: publish the v1.13.0 release (PyPI), and host /model2data/spec/metrics/0.1.0/ on the website per PUBLISHING.md.

🤖 Generated with Claude Code